FTW

Section: MINTLIB LIBRARY FUNCTIONS (3)
Updated: 3 March 1993
Index Return to Main Contents

NAME

ftw - walk a file tree

SYNOPSIS

#include <ftw.h>

int ftw(char *path, int (*fn)(char *, struct stat *, int), int depth);

DESCRIPTION

ftw recursively descends the directory hierarchy rooted in path. For each object in the hierarchy, ftw calls the user-supplied function fn, passing it a pointer to a null-terminated character string containing the name of the object, a pointer to a stat structure containing information about the object, and an integer. Possible values of the integer, defined in the <ftw.h> header file, are FTW_F for a file, FTW_D for a directory, FTW_DNR for a directory that cannot be read, and FTW_NS for an object for which stat could not successfully be executed. If the integer is FTW_DNR, descendants of that directory will not be processed. An example of an object that would cause FTW_NS to be passed to fn would be a file in a directory with read but without execute (search) permission. ftw visits a directory before visiting any of its descendants. The tree traversal continues until the tree is exhausted, an invocation of fn returns a nonzero value, or some error is detected within ftw (such as an I/O error). If the tree is exhausted, ftw returns zero. If fn returns a nonzero value, ftw stops its tree traversal and returns whatever value was returned by fn. If ftw detects an error, it returns -1, and sets the error type in errno. ftw uses one file descriptor for each level in the tree. The depth argument limits the number of file descriptors so used. If depth is zero or negative, the effect is the same as if it were 1. Depth must not be greater than the number of file descriptors currently available for use. ftw will run more quickly if depth is at least as large as the number of levels in the tree.

NOTES

Note that MiNT limits each process to 32 file descriptors. Since three are normally used for standard input, output and error output, only few remain. C library functions like this are usually only found after a similar version has already been written by the programmer.

BUGS

Because ftw is recursive, it is possible for it to terminate with a memory fault when applied to very deep file structures. Symbolic links are reported to the user-supplied function as FTW_F.

This document was created by man2html, using the manual pages.
Time: 11:14:51 GMT, June 22, 2025